home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / UTIL / SCREEN / LIFEGUARD / !Lifeguard / Documents / FileSpec < prev    next >
Text File  |  1992-09-30  |  11KB  |  290 lines
  1. File format for Lifeguard 1.08 Effects Modules (&400, GuardMod)
  2. ===============================================================
  3.  
  4.  
  5. ===========================================================================
  6. Offset  Length   Contents
  7. (dec)   (dec)
  8. ---------------------------------------------------------------------------
  9. 0       8        GUARDMOD (&52415547, &444F4D44)
  10. 8       4        Version number of Lifeguard that this effect module was
  11.                  written for, times by 100 (eg. 1.08*100=108)
  12. 12      4        Flags (see below)
  13. 16      4        Required mode for effect (see below)
  14. 20      28       Short name of the effect (padded with zeros)
  15. 48      34       First line of long name of the effect (padded with zeros)
  16. 82      34       Second line of long name of the effect (padded with zeros)
  17. 116     34       Third line of long name of the effect (padded with zeros)
  18. 150     34       Author's name (padded with zeros)
  19. 184     4        B initialise_code
  20. 188     4        B vsync_code
  21. 192     4        B finalise_code
  22. 196     4        Pointer to options window template, 0 if no window
  23.  
  24.  ***   All values below here can be ommitted if offset 196 is 0   ***
  25.  
  26. 200     4        Pointer to routine to set options window icons   \
  27. 204     4        Pointer to routine to read options window icons  | see below
  28. 208     4        Pointer to routine to be called on Poll event    /
  29.  
  30. ===========================================================================
  31.  
  32.  
  33. NB: Any of the entry points can be left out (by replacing them with
  34. --  MOVS PC,R14) if you wish. If the vsync_code entry is left out, however,
  35.     all that will happen is that the screen will turn black (because
  36.     Lifeguard will change mode to the one you have asked for, call the
  37.     intialise code and then not call your code again until it gets to the
  38.     finalise entry).
  39.  
  40.     R2-R5 can be used for storing things in. These will start as all 0 on
  41.     the call to Initialise, then they will remain constant from call to call
  42.     until the Finalise entry is called, after which the values are
  43.     forgotten.
  44.  
  45.     Remember that your code must be fully relocatable, as it will move about
  46.     when Lifeguard is first loaded, and when the user removes effects above
  47.     your one in the effects file.
  48.  
  49.     You should try to make your code mode-independent (see below). You can
  50.     use calls to ColourTrans, as this is guaranteed to be loaded.
  51.  
  52.  
  53. Initialise code
  54. ---------------
  55.  
  56. On entry:
  57.    R0    = Version number of Lifeguard*100
  58.    R1    = Current screen mode
  59.    R2-R5 = 0
  60.    R6    = Address of screen parameters block (see below)
  61.    R13   = Stack
  62. On exit:
  63.    R0    = 0 if effect refuses to initialise
  64.    R2-R5 = Work registers
  65.    All registers above R5 (R6-R13) must be preserved
  66.  
  67.    This code is called once, when the screen is due to be 'blanked'. It
  68. should claim any workspace needed and check that everything is OK for the
  69. effect to be displayed. If the effect cannot start up for any reason, R0
  70. should be 0 on exit. Any other value than 0 will be assumed to mean that the
  71. effect has initialised OK. The code MUST preserve ALL registers other than
  72. R0-R5.
  73.    Note that, although Lifeguard will try to change to the mode that you
  74. request, it may not be able to, eg. because of insufficient memory.
  75. Therefore, if your code is not guaranteed to work in ALL modes, it should
  76. check the mode given in R1, and refuse to initialise if it doesn't like it.
  77.  
  78.  
  79. VSync code
  80. ----------
  81.  
  82. On entry:
  83.    R0    = 0
  84.    R2-R5 = Work registers
  85.    R6    = Address of screen parameters block (see below)
  86.    R13   = Stack
  87. On exit:
  88.    R0    = -1 means effect has finished
  89.    R2-R5 = New work registers
  90.    All registers above R5 (R6-R13) must be preserved
  91.  
  92.    This code is called on every available VSync while the effect is being
  93. displayed. This code should display the effect, move it, whatever. The code
  94. MUST preserve ALL registers.
  95.    If R0 = -1 on exit then Lifeguard will finalise your effect and choose
  96. another one. This is used by 'Fade' to start another effect when the desktop
  97. screen has faded out.
  98.    Remember that you are still in the Desktop, so the code should be as
  99. legal as possible. You can write directly to the screen, if you are sure
  100. of the mode, and if you use legal calls to work out the screen address.
  101.  
  102.  
  103. Finalise code
  104. -------------
  105.  
  106. On entry:
  107.    R2-R5 = Work registers
  108.    R6    = Address of screen parameters block (see below)
  109.    R13   = Stack
  110. On exit:
  111.    All registers must be preserved
  112.  
  113.    This code is called when the effect is being closed down. It should
  114. release any workspace, etc. It MUST preserve ALL registers.
  115.  
  116.  
  117. Mode
  118. ----
  119.  
  120.     Normally, Lifeguard will attempt to change to the mode specified in the
  121. effect's header, by using a Wimp_SetMode followed by a VDU 22,mode to reset
  122. the palette, etc. If you specify the mode as -1 then the mode will not be
  123. changed - this may be used in conjuction with bit 2 of the flags (see below).
  124. Note that if you set the mode number to -1 then the screen will still be
  125. wiped, unless you do set bit 2 of the flags.
  126.     Note that you should try to make your effect mode-independent - ie. set
  127. the required mode to -1. The main reasons for this are that if you change to
  128. a lower-resolution mode then the windows all move a little bit, and if you
  129. move to a smaller screen size mode then the windows can move quite a lot.
  130.  
  131.  
  132. Screen parameters block
  133. -----------------------
  134.  
  135.     Lifeguard will pass you a pointer in R6 to a block of memory containing
  136. information about the current screen mode. The format of the block is as
  137. follows:
  138.  
  139.     R6 +  0 = Number of colours (ie. 2,4,16 or 256)
  140.     R6 +  4 = XEigFactor (number of bits to shift a pixel value leftwards to
  141.                           get the value in OS Units - eg. 1 for mode 12).
  142.     R6 +  8 = YEigFactor (similarly for Y direction)
  143.     R6 + 12 = Number of pixels across (eg. 640 for mode 12)
  144.     R6 + 16 = Number of pixels down (eg. 256 for mode 12)
  145.     R6 + 20 = Screen width in OS Units (eg. 1280 for mode 12)
  146.     R6 + 24 = Screen height in OS Units (eg. 1024 for mode 12)
  147.     R6 + 28 = Address of start of displayed screen (eg. &1FEC000)
  148.     R6 + 32 = Screen mode (eg. 12)
  149.     R6 + 36 = One horizontal pixel in OS Units (ie. 1<<XEig) (eg. 2)
  150.     R6 + 40 = One vertical pixel in OS Units (ie. 1<<YEig) (eg. 4)
  151.     R6 + 44 = Address of screen fade routine (see below)
  152.  
  153.  
  154. Screen fade routine
  155. -------------------
  156.  
  157.     This routine, provided by Lifeguard, can be used to dim the screen. This
  158. can be used as a normal fade to black, or can be made to go only half way.
  159. This can be useful for effects which leave the original desktop screen in
  160. place and move it around (eg. RainyDay, Puzzle), as if the original screen
  161. was largely a bright colour then the effect wouldn't help much. Call the
  162. routine with the start position in R0 and the end position in R1. The
  163. positions are the 'degrees of fade', 0-15 with 0 as black and 15 as normal
  164. colours.
  165.  
  166.  
  167. Options window
  168. --------------
  169.  
  170.     From version 1.06, Lifeguard will allow your effect to have an options
  171. window which allows the user to customise your effect. The template should be
  172. in your effect module (see the example effects for a routine to include the
  173. template in your file).
  174.     Icon 0 should be an 'OK' button. Icon 1 should be a 'Cancel' button.
  175. Apart from this the window can contain anything you like. Remember that you
  176. can use WimpExtension 3D icons and pointer changes in your window if you
  177. don't set the 'Auto-Redraw' bit. The 'ptr_menu' and 'ptr_write' pointers are
  178. guaranteed to be available. Part of the WimpExtension manual is included in
  179. the file 'WimpExtMan' so you can use these features. You can also use the
  180. icon-handling features of WimpExtension.
  181.     You must provide 3 routines for dealing with your window:
  182.  
  183.  
  184. Window-Set code
  185. ---------------
  186.  
  187. On entry:
  188.   R0 = Window handle
  189.  
  190.     This routine should set the window's icons according to the status of
  191. stored information in the effect module. The window will not be visible when
  192. this routine is called.
  193.  
  194.  
  195. File-Set code
  196. -------------
  197.  
  198. On entry:
  199.   R0 = Window handle
  200.  
  201.     This routine should set the stored information in the effect module
  202. according to the window's icons.
  203.  
  204.  
  205. Event code
  206. ----------
  207.  
  208. On entry:
  209.   R0 = Mouse_Click (6) or Menu_Selection (9)
  210.   R1 = Pointer to Poll block
  211. On exit:
  212.   If R0 = 'MENU' (&554E454D) then
  213.     R1 = pointer to menu block
  214.     R2 = X Pos for menu
  215.     R3 = Y Pos for menu
  216.  
  217.     This routine should deal with mouse clicks and menu selections in your
  218. window. You can create menus by exiting with the parameters for
  219. Wimp_CreateMenu in R1, R2, R3, and 'MENU' in R0.
  220.  
  221.  
  222. Flags
  223. -----
  224.  
  225. ===========================================================================
  226. Bit     Meaning if set    
  227. ---------------------------------------------------------------------------
  228. 0       Effect is enabled
  229. 1       Effect is selected
  230. 2       Needs the desktop screen in place
  231. 3       Inhibit dimming
  232. 3-31    Reserved; MUST BE 0
  233. ===========================================================================
  234.  
  235. NB: Bits 0 and 1 must be set to 0 in the EffectMod file. These bits are set
  236. --  by Lifeguard in the Effects file if the effect is enabled or selected.
  237.  
  238.     The only bits that should currently be set by effects writers are bits 2
  239. and 3. If bit 2 is set then Lifeguard will not wipe the screen before
  240. starting the effect. This is so that you can write effects that use the old
  241. screen, such as 'Puzzle'. If bit 3 is set than Lifeguard will never dim the
  242. screen before entering your effect. This is for effects like 'Fade' which
  243. wipe the screen anyway.
  244.  
  245.  
  246. GuardRM
  247. -------
  248.  
  249.     The Guard relocatable module is used to detect keypresses and mouse
  250. clicks. It also provides an emergency or out-of-desktop screen blanker which
  251. simply turns the screen black. It provides several SWIs. Apart from the two
  252. below, you SHOULD NOT USE the SWIs, even if you think you know what they do
  253. (it's pretty obvious from their names). You shouldn't have to use them
  254. anyway - anything like changing the blanking delay should be done by the
  255. user, not by another program.
  256.     There are two SWIs you can use: Guard_ReadRandom and Guard_LargeRandom.
  257. These are outlined below:
  258.  
  259.  
  260. SWI Guard_ReadRandom
  261.  
  262. On entry:
  263.     R0   = Maximum limit (1-8192)
  264. On exit:
  265.     R0   = Random number 0-limit
  266.     Flags preserved
  267.  
  268.     This SWI returns a random number in the range 0-R0. The maximum limit is
  269. 8192. The number is brought within the correct range simply by repeatedly
  270. subtracting the range until the number is within the range. If your range is
  271. a power of two therefore, it is quicker to set a range of 8192 (or anything
  272. larger) and then ANDing the number to get it in range.
  273.     The random number routine is very simple, but should be good enough for
  274. most purposes. It is seeded with the monotonic time when the Guard module is
  275. first loaded.
  276.  
  277.  
  278. SWI Guard_LargeRandom
  279.  
  280. On entry:
  281.     R0   = Maximum limit (1-65535)
  282. On exit:
  283.     R0   = Random number 0-limit
  284.     Flags preserved
  285.  
  286.     This is the same as Guard_ReadRandom, except that it can produce numbers
  287. in the range 0-65535. The penalty for this is that it is slightly slower.
  288. Therefore ReadRandom should be used where possible; only use LargeRandom
  289. where you have to.
  290.